🚀 Deployed on https://6a70758aa8f69f194b32ab62--epic-agnesi-957267.netlify.app

@kp992 thanks for opening this. Excellent work! It is exciting to see how close we are now.

From my review it looks like there a just a few issues and features we need before launch.

Bugs:

1. LHS TOC menu flickers when using the Home page or a top level Part section. It is like it has an auto-stow feature that is triggering when pages are reloaded. It doesn't look great when pages are refreshed.
2. Code block formatting has too much indentation for Solution blocks

Features:

1. I see a bunch of new export notebooks being added to the yaml headers of each lecture. Do we need to do some development work on supporting the download notebook link in the theme?
2. Is index support on the jb2 / mystmd roadmap?

• check if theme regression is occurring. Clicking on a chapter briefly shows a malformed webpage that disappears to the LEFT. NEEDS REVIEW.

Refreshed against the current toolchain

Branch is up to date with main and now builds with the QuantEcon fork of the MyST CLI and the new theme repo. The PR description has been rewritten to describe the resulting setup.

The HTML build was never using the fork

This is the part worth reading. jupyter book build cannot use our fork, and had been quietly building the preview with upstream mystmd this whole time. jupyter-book 2.x is a thin Python shim: jupyter_book/__main__.py execs a compiled mystmd bundle vendored inside its own wheel (jupyter_book/dist/jupyter-book.cjs) and exposes no hook to point it at a different CLI. The npm install -g of the fork in this workflow was installing a CLI that the build step then ignored. Only build-ipynb.yml, which calls myst directly, was ever exercising the fork.

The evidence is in the last run before the fix — the jupyter-book HTML build emitted 27 × 'output' unknown export output extension: exports/<page>.ipynb, since the per-page ipynb export is a fork feature (myst-to-ipynb, qe-v1) that upstream doesn't know about. The same commit built by the fork's myst build --ipynb emitted none and exported 23 clean notebooks.

The HTML build now runs myst build --html --execute with the fork's CLI, and the pip install jupyter-book step is gone — it was only putting a second, conflicting mystmd on the image. Same engine and same flags either way; jupyter-book 2.x is mystmd, this is just our build of it.

Three other things the review turned up

• The JAX lectures were rendering ModuleNotFoundError cells. This job installed only myst_requirements.txt, while the jupyter-book 1.x job on main installs jax[cuda13] separately, so jax_intro, autodiff and numpy_vs_numba_vs_jax had been executing to import errors through green builds. Same install added here.
• myst.yml's TOC had drifted from _toc.yml — autodiff and the new polars lecture missing, workspace listed twice, one part title stale. The two files now list exactly the same 27 pages.
• project.github pointed at lecture-python-programming.myst, which only survives as a rename redirect. The theme derives the notebook-launch repo from that value plus a .notebooks suffix, so a stale name means broken launch buttons. Corrected.

Also: Node 20 → 24 (the theme's .nvmrc), remaining actions to current majors (clears the Node 20 removal deprecation), the unused configure-pages step dropped since this job deploys to Netlify rather than Pages, and seven committed execution artifacts removed (foo.py, us_cities.txt, test_table.csv and friends — all written by %%file cells in the lectures, all gitignored, none present on main).

Left for a decision

Nothing fails the build on a notebook execution error — that is exactly how the JAX breakage stayed invisible. main gained a gate for the jupyter-book 1.x path in #588; the fork's CLI has myst build --strict for the same job here, but it is worth turning on only after the remaining build diagnostics are triaged, otherwise it will fail on unrelated warnings.

This is supporting @DrDrij review of quantecon-theme.mystmd

Why this branch builds with QuantEcon/mystmd rather than jupyter-book

Retitled to reflect what the build chain actually does. The short version: jupyter-book cannot be pointed at our fork, so building through it silently discards every QuantEcon feature we depend on.

jupyter-book ignores the fork, even when the fork is installed

jupyter-book 2.x is a Python shim that execs a mystmd bundle vendored inside its own wheel (jupyter_book/dist/jupyter-book.cjs). Installing QuantEcon/mystmd globally with npm afterwards puts our myst on PATH, but jupyter-book never calls it.

This is not a theoretical concern — it is visible in our own CI history. In the last run that built with jupyter book build (4314bc19, 2026-07-31), the Verify mystmd version step reported v1.10.1 (qe-v8), confirming the fork was installed and first on PATH. The build in the very next step then emitted 23 errors of the form ⛔️ unknown export output extension: exports/<lecture>.ipynb — one per lecture declaring an ipynb export. That export format is a fork-only capability, so those errors prove the build was running upstream mystmd, not ours. Under myst build with the fork, the same 23 exports produce zero errors.

The Verify mystmd version step is therefore misleading on its own: it verifies the standalone binary, not the engine jupyter-book actually execs. It reports a reassuring qe-v8 while the build beside it uses something else.

What we would lose

The fork is at qe-v8 on upstream_base: 1.9.1 and carries thirteen QuantEcon features, most of them load-bearing for a book-style render: CommonMark ipynb export with image attachments, book-style numbering, Roman-numbered part dividers with a continuous chapter counter, section-level scope for proof:* / figure / equation numbering, the full title→heading chain per section, shared counters across proof kinds, Pandoc-style fancy ordered lists, citation scanning that respects inline code spans, numbering.code honouring the book prefix, and amsthm-convention unnumbered proofs. None of these exist upstream, so none of them survive a jupyter book build.

What is and is not migrated

Migrating the production chain is deliberately out of scope here and belongs in its own PR: it covers the PDF build (currently jb build --builder pdflatex, with a typst book-pdf export stubbed in myst.yml), the notebook downloads (currently the sphinx-tojupyter custom builder, already prototyped as myst build --ipynb in build-ipynb.yml), the weekly execution cache, and the Anaconda execution tests.

Known issue on this branch

Cold-cache builds currently fail. The execution cache key is hashFiles('lectures/**/*.md'), so editing any single lecture invalidates all ~25 notebooks and forces a full re-execution; jax_intro.md's kernel is then killed (Connection lost → Kernel: restarting → Unhandled error, exit 1) with no Python traceback.

This is not caused by mixing build systems — ci.yml installs no jupyter-book at all, and publish.yml / cache.yml do not run on pull requests. Comparing the last green cold run against the failures: same JAX 0.11.0, same 25 notebooks executed cold, same peak concurrency of 8, near-identical overlapping peers. The only difference is the engine — jax_intro.md executed in 25 s under jupyter-book's vendored mystmd and dies at 66 s under the fork's CLI. No timeout explanation survives either, since numpy.md took 99 s in the green run and built fine.

Two things worth doing before diagnosing further: pin the fork clone to the qe-v8 tag rather than --branch main, since the engine is currently a moving target between runs of the same commit; and capture free -m, nvidia-smi and dmesg -T | grep -i "killed process" in an if: always() step, because a SIGKILL with no traceback is consistent with the host OOM killer but that remains unconfirmed.

Cold-cache execution failure: diagnosed, fixed, validated

Closing out the "known issue" from my earlier comment. The kernel death was not the engine and not host memory — it was a GPU preallocation race, confirmed by an instrumented run and fixed in two commits.

Diagnosis (instrumented run 30806359596)

A 5-second GPU/host-memory sampler ran beside the failing build. The GPU timeline told the whole story on one line: 0 → 11,305 MiB → 14,727 → 3,427 → 0 on the g4dn's 15,360 MiB T4.

The three JAX lectures (jax_intro, autodiff, numpy_vs_numba_vs_jax) execute concurrently (myst parallelism = cpus−1 = 7). The first JAX kernel to touch the GPU preallocated JAX's default 75% — 11,305 MiB. jax_intro's kernel lost that race, clamped to the ~3.4 GiB remainder, and aborted ~40 s later when a cell outgrew the pool — an XLA fatal in the kernel process, which is why there was no Python traceback. dmesg was clean: no OOM-killer records, no segfaults, so the host is exonerated. The only kernel event in the entire build was jax_intro's; the 11.3 GiB holder's exit was a clean post-build reap.

This also explains the confusing history: the jupyter-book-era cold run went green because jax_intro won the race that day (verified from its HTML artifact — JAX cos on 50M elements in 0.0022 s vs NumPy's 1.07 s, i.e. genuinely on GPU), and main never hits this because the JB1 build executes notebooks sequentially. The engine swap changed execution phasing, not semantics — which is why the failure appeared engine-correlated for three runs straight.

Fix and validation

Validation run 30806924581: fully cold (all 25 notebooks executed), zero kernel restarts, jax_intro built in 46 s (vs 45 s in the healthy jupyter-book-era cold run), peak GPU usage 4,217 MiB with no preallocation spike, dmesg clean. The f541ccc run is a second cold validation by construction, since changing the cache key forces one.

Structural fixes, so this class of bug can't ship green again

The engine swap originally shipped green because the execution cache key hashed only lectures/**/*.md — a warm cache replayed old outputs and the new engine never executed a notebook. The key now hashes the requirements and the workflow file itself, so any engine SHA bump, JAX bump, or XLA env change forces a cold, genuinely-executed build automatically. The memory sampler and dmesg read-back stay in the workflow as standing telemetry.

One upstream follow-up filed from this: myst reports a dead kernel as a bare Unhandled error with no notebook, cell, cause, or kernel stderr — QuantEcon/mystmd#77 asks for the diagnostics that would have made this a one-look failure instead of an instrumented investigation.